package com.smart.community.region.service;

import com.smart.community.region.entity.Region;
import com.smart.community.region.dto.RegionTreeVO;

import java.util.List;

/**
 * 区域缓存服务接口
 * 
 * 功能说明：
 * 1. 为区域表的高频查询提供缓存支持
 * 2. 实现缓存降级机制，确保系统稳定性
 * 3. 提供缓存清理和预热功能
 * 4. 严格按照《Java后端SpringBoot代码开发规范.md》实现
 * 
 * @author Wu.Liang
 * @since 2025-01-30
 */
public interface RegionCacheService {

    // ==================== 区域详情缓存 ====================

    /**
     * 根据区域ID获取区域信息（带缓存）
     * 
     * @param regionId 区域ID
     * @return 区域信息
     */
    Region getRegionById(Long regionId);

    /**
     * 根据区域编码获取区域信息（带缓存）
     * 
     * @param regionCode 区域编码
     * @return 区域信息
     */
    Region getRegionByCode(String regionCode);

    /**
     * 根据区域类型获取区域列表（带缓存）
     * 
     * @param regionType 区域类型
     * @return 区域列表
     */
    List<Region> getRegionsByType(Integer regionType);

    /**
     * 获取子区域列表（带缓存）
     * 
     * @param parentId 父区域ID
     * @return 子区域列表
     */
    List<Region> getChildRegions(Long parentId);

    /**
     * 获取区域层级路径（带缓存）
     * 
     * @param regionId 区域ID
     * @return 层级路径
     */
    List<Region> getRegionPath(Long regionId);

    /**
     * 获取区域树形结构（带缓存）
     * 
     * @param parentId 父区域ID
     * @return 区域树形列表
     */
    List<RegionTreeVO> getRegionTree(Long parentId);

    /**
     * 获取所有启用的区域列表（带缓存）
     * 
     * @return 启用的区域列表
     */
    List<Region> getEnabledRegions();

    /**
     * 获取所有区域列表（带缓存）
     * 
     * @return 所有区域列表
     */
    List<Region> getAllRegions();

    /**
     * 获取所有父区域ID（带缓存）
     * 
     * @param regionId 区域ID
     * @return 父区域ID列表
     */
    List<Long> getAllParentRegionIds(Long regionId);

    /**
     * 获取所有子区域ID（带缓存）
     * 
     * @param regionId 区域ID
     * @return 子区域ID列表
     */
    List<Long> getAllChildRegionIds(Long regionId);

    // ==================== 缓存管理 ====================

    /**
     * 清除区域相关缓存
     * 
     * @param regionId 区域ID
     */
    void clearRegionCache(Long regionId);

    /**
     * 清除区域编码相关缓存
     * 
     * @param regionCode 区域编码
     */
    void clearRegionCodeCache(String regionCode);

    /**
     * 清除区域类型相关缓存
     * 
     * @param regionType 区域类型
     */
    void clearRegionTypeCache(Integer regionType);

    /**
     * 清除所有区域缓存
     */
    void clearAllRegionCache();

    /**
     * 预热区域缓存
     * 
     * @param regionIds 区域ID列表
     */
    void warmUpRegionCache(List<Long> regionIds);

    /**
     * 预热区域类型缓存
     * 
     * @param regionTypes 区域类型列表
     */
    void warmUpRegionTypeCache(List<Integer> regionTypes);

    /**
     * 获取缓存统计信息
     * 
     * @return 缓存统计信息
     */
    Object getCacheStatistics();
} 